Replace `toc.follow` with `toc.integrate` in mkdocs.yml features.
Pages with both chapter nav and a TOC (e.g. examples/lambda-functions/)
were rendering two side panels; the integrated TOC consolidates them
into the left sidebar under the active page entry.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

mkdocs-material 9.x bundles mermaid + initialize call with themeCSS
that follows the active palette. The mermaid2 plugin was overriding
this with its own loader, leaving diagrams unstyled on the dark
scheme (unreadable on the dark page background).

Removing the plugin lets mkdocs-material auto-theme diagrams to the
current palette — light-on-dark glyphs in slate scheme.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Previous attempt to drop mermaid2 in favor of mkdocs-material native
was a misread: native mermaid support is Insiders-tier (paid) only.
Free version needs the plugin to load mermaid.js and call initialize.

mkdocs-mermaid2-plugin 1.2.3 with:
- fence_mermaid (not _custom) — produces <div class="mermaid"> markup
  and lets the plugin call mermaid.initialize itself. The _custom
  variant assumes Material's bundle will bridge window.mermaidConfig
  to mermaid.initialize, which only happens in Insiders.
- theme: base + themeVariables aligned with simple-container.com
  palette: #07070f bg, #1e1b4b primary, #a855f7 borders/lines,
  #22d3ee accents, #eeeeff text.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

The Architecture Overview diagram had hardcoded pastel classDef
fills (#e1f5fe, #e8f5e8, #fff8e1) that override the global mermaid
theme variables. On the dark page background these rendered as
near-white blobs with dark green/blue text — unreadable.

Replace with dark fills aligned to landing palette while keeping
three-way distinction between subgraphs:
- parentStack: dark blue (#0c1f3f / #3b82f6 stroke / #dbeafe text)
- serviceStack: dark purple (#1a1740 / #a855f7 / #e9d5ff)
- deployFlow: dark cyan (#0f2a2e / #22d3ee / #cffafe)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Per landing/.agents/design/2026-05-25/docs-refactor/ plan — branch 1
of the content refactor (promo cuts + index rewrite + main-concepts
trim).

Deletions (~1,700 lines of marketing prose):
- concepts/motivation.md ("game-changing approach", "500x speed",
  duplicates landing). 193 lines.
- reference/use-cases.md ("10 reasons to buy SC" with quantified
  pitches in every entry). 230 lines.
- advanced/scaling-advantages.md ("SC vs Terraform/Pulumi" comparison
  with marketing language). 912 lines.
- advanced/compare-with-other-tools.md ("Why SC wins" positioning
  tables). 384 lines.

mkdocs.yml nav: drop "Why Simple Container", "Use Cases", "Scaling
Advantages", "Tool Comparisons" entries.

index.md: rewrite as a five-link landing pad. One factual paragraph
describing what SC is. Links to Install / Quickstart / Concepts /
Reference / Guides. Brief Forge mention (emits SC YAML natively via
MCP). Cuts: "500x faster", "70% reduction", "80% staff reduction",
"game-changing", "enterprise-grade", all emoji-decorated section
headers.

concepts/main-concepts.md: heavy rewrite. Keeps the architectural
substance (parent/child stacks, what each owns, when each changes,
comparison table, resource-sharing pattern, double-resources nesting
note) and the mermaid diagram (emojis stripped from labels per doc
01 §2.1, dark classDef fills for dark-theme readability). Cuts §4-§6
"quantified scaling benefits" + "real-world scenarios" + "conclusion"
sections — all promotional. Adds a brief Forge mention where the
programmatic / MCP interface is referenced. 282 → 138 lines.

guides/index.md: redirect dangling link from deleted scaling-advantages
to advanced/best-practices.

Two ai-assistant orphan pages still reference the deleted
scaling-advantages.md (developer-mode, devops-mode). Those are deferred
per doc 05 §4 — ai-assistant content audit is a separate workstream.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

# Conflicts:
#	docs/docs/concepts/main-concepts.md

Cross-cutting cleanup across ~70 live pages.

Emoji sweep (per landing/.agents/design/2026-05-25/docs-refactor/01 §2.1):
- Stripped 600+ AI-slop emoji instances on live pages: ✅, ❌, 🚀, 🎯,
  🔧, 💡, ⚡, 📈, 💰, 1️⃣–🔟, plus dozens of decorative pictograms
  (🛠 ⭐ 🌟 🔥 📦 🔐 🌐 ☸ 📚 🔗 🧠 📖 👥 🏗 📋 📄 🔄 🧑‍💻 👩‍💻 🤖 ✨ 🎉
  💯 📝 📊 🎛 📁 🔍 🚨 📌 🛡 🔹 📞 …).
- ai-assistant/* deep pages excluded from the sweep — they're queued
  for the separate content audit per doc 05 §4.
- Box-drawing characters (└ ├ │ ─) kept since they're typographic, not
  pictographic.
- ✅/❌ in table cells converted to "Yes"/"No" where they were the
  sole signal. Decorative ones removed.
- Followed by a parser-aware bold-marker fixup so emoji removal didn't
  leave `** text **` patterns (which markdown won't render as bold).

Link audit (per doc 02 §14):
- concepts/template-placeholders.md "See Also" — fixed relative paths
  (user-reported example): supported-resources.md → ../reference/...
  examples/ → ../examples/README.md, authentication.md → ../guides/secrets-management.md
- examples/secrets/README.md — replaced phantom reference/cli.md and
  guides/{client,server,security}-configuration.md with the existing
  reference/supported-resources, reference/service-available-deployment-schemas,
  guides/secrets-management, guides/container-security.
- guides/cicd-github-actions.md + examples/cicd-github-actions/README.md —
  removed dangling references to advanced/{deployment-patterns,monitoring}.md,
  redirected to existing advanced/best-practices.md and guides/container-security.md.
- examples/kubernetes-affinity/* — phantom high-availability/ and
  performance-optimization/ refs removed; guides/kubernetes-native/
  → guides/parent-pure-kubernetes.md.
- examples/kubernetes-vpa/README.md — anchor #vertical-pod-autoscaler-vpa
  → concepts/vertical-pod-autoscaler.md (no anchor needed).
- reference/supported-resources.md — stale ./howto/ link → examples/README.md.
- Mass-fixed 30+ unrecognized-relative-links by adding /README.md or
  /index.md suffix per mkdocs hint output.
- Build now reports 0 link warnings on live pages (all remaining
  warnings are inside ai-assistant/* orphan pages, marked not_in_nav).

Nav surfacing (per doc 05):
- Added Troubleshooting and Compliance nav sections (1 page each).
- Surfaced 6 previously-orphan live guide pages:
  service-steps-to-deploy, cicd-github-actions, container-security,
  dns-management, gke-version-management, resource-adoption.
- Surfaced concepts/vertical-pod-autoscaler.md.
- Moved user-guides/container-security.md → guides/container-security.md
  (different content from troubleshooting/container-security.md; both
  kept, both surfaced under correct nav sections).
- Removed empty user-guides/ directory.
- Added AI Assistant nav entry pointing at the rewritten
  ai-assistant/index.md (terse overview per doc 05 §4 Option B).
- not_in_nav directive added for the 9 ai-assistant deep pages so
  they remain reachable by URL but don't generate nav warnings.

ai-assistant/index.md rewrite:
- Stripped marketing voice (purpose statements, "intelligent setup",
  "Two-Mode Architecture" emoji-decorated section). New shape: what
  the CLI does, two modes with example commands, MCP server section,
  pointer to the deeper docs that will surface after content audit.
  174 → 34 lines.

quick-start.md `sc provision` (user-reported):
- Split Step 4 (Deploy) into Step 4 (Provision the parent stack) and
  Step 5 (Deploy your service). The previous version skipped the
  parent-stack provisioning step — required before any service deploy
  because shared resources (S3 buckets, templates, registrar) must
  exist first. Step 6 is the new Verify.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…amples

Per landing/.agents/design/2026-05-25/docs-refactor/03 — verify every
server.yaml example uses the canonical three-level resources nesting
(resources → registrar/resources → env → resources → name).

Bugs found and fixed:

1. getting-started/quick-start.md — the parent-stack example was
   missing the inner `resources:` map between the env (`prod`) and
   the resource name (`main-bucket`). Corrected to add the inner
   `resources:` key + a `template:` reference + a `name:` field.

2. guides/parent-gcp-gke-autopilot.md — the second resources block
   (Private VPC example, line ~190) had only one level of `resources:`,
   skipping the outer per-stack container. Added the outer level and
   re-indented the nested content accordingly.

3. reference/supported-resources.md — replaced the generic intro with
   an explicit canonical YAML skeleton at the top of the page showing
   all three `resources:` levels with comments labeling each. Cites
   `pkg/api/server.go` ServerDescriptor as the source of truth.

The other audited files (guides/parent-ecs-fargate.md,
guides/parent-pure-kubernetes.md) already had the correct nesting.

Build: mkdocs build with 0 link warnings on live pages.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

mkdocs-material requires a blank line between a paragraph and the
list that follows it. Patterns like

  **Bucket-Specific Variables** (where BUCKET_NAME is …):
  - GCS_<BUCKET_NAME>_BUCKET — Bucket name
  - GCS_<BUCKET_NAME>_LOCATION — Bucket location

render as a single run-on paragraph instead of an unordered list.

User-reported on
  http://127.0.0.1:8000/concepts/template-placeholders-advanced/#gcp-bucket

Script targets the safe subset: only inserts a blank line when the
preceding line ends with `:` or `**` AND the next line starts with
a top-level `- ` (or `*`, `+`). Skips inside fenced code blocks,
nested list items, headings, and ordered-list continuations.

47 pages fixed across guides, references, examples, concepts,
compliance, and troubleshooting.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>